.TH SLDOC 1L "Dec 1996" "sldoc 1.00" "USER COMMANDS"
.ds pG \fBsldoc\fP
.ds b[ \fR[\|\fP
.ds b] \fR\|]\fP
.ds b| \fR\|\(br\|\fP
.SH NAME
sldoc \- C/S-Lang command file documentation facility
.SH SYNOPSIS
\*(pG
.BI \-c " file .\|.\|."
.br
\*(pG
.BI \-i " file .\|.\|."
.br
\*(pG
.BI \*(b[\-l\*(b|\-t\*(b] " name .\|.\|."
\"
.SH DESCRIPTION
\*(pG is an executable
.BR vamps (1L)
script which facilitates documentation for S-Lang command (and C source
code) files.
Documentation text is extracted from comments in the command files,
which are usually placed in library directories. All output is
printed on standard output. 
.PP
The first form extracts documentation text from C source code files. If
the output is saved in a file, that file can be used by the other forms.
.PP
The second form above builds an index table for use by the third
form from the named S-Lang
.IR file s
(by convention suffixed with
.RB `` .sl '')
and/or files created with the
.B \-c
option. Index files need to be (re)created whenever documentation
entries (see below) are added to, removed from, or renamed in
library files by redirecting the final output to a file named
.BR sldoc.idx .
.PP
The third form above prints the documentation text for all
.IR name s
on standard output, using the index information in the file
.BR sldoc.idx .
A
.I name
is either an S-Lang library command name or the name of a library
file, for which all entries are then printed. If invoked without
options, raw ascii mode is used. The
.B \-l
option formats output for use with
.BR LaTeX ;
the
.B \-t
option formats output for use by the
.BR groff ,
.B nroff
and/or
.B troff
typesetting programs.
.\"
.SS Documentation Format
Documentation text is contained within comment blocks in the
appropriate S-Lang command files and follows a few simple conventions
outlined below.
See for examples the files in the
.B slash
default library directory.
.TP
.B \(bu
All lines in the documentation text contain a percent
.RB ( % )
character at the first position.
.TP
.B \(bu
The first line specifies the index name in the form
.BI %I: name
and should not contain whitespaces or other text; multiple names
in a single entry are permitted.
.TP
.B \(bu
Initial space and
.SM TAB
characters after the percent character are stripped.
.TP
.B \(bu
Lines starting with
.B %@
are copied verbatim without adjustment or line filling. Depending
on the output mode, typeface may be changed. Initial spaces are
stripped, but
.SM TAB
characters are not.
.TP
.B \(bu
Words placed inside matching
.B @
character pairs are printed in the verbatim mode typeface.
.TP
.B \(bu
A new paragraph is started by a line containing only the percent
character. Line space is also inserted before and after verbatim
text.
.PP
Documentation text in C source code file is similarly contained in
C comment blocks, except that the percents are replaced by asterikses
and the name id is prefixed with a slash.
.\"
.SH FILES
.B sldoc.idx\t
function/file index table
.\"
.SH EXAMPLES
The following command creates an alphabetically sorted index for
all S-Lang command files in the current working directory:
.PP
.RS
.nf
.ft CW
sldoc -i *.sl | sort > sldoc.idx
.ft R
.fi
.RE
.PP
To extract all documentation contained in a file named
.B my_lib.sl
and format into TeX commands, use:
.PP
.RS
.nf
.ft CW
sldoc -l my_lib.sl
.ft R
.fi
.RE
.PP
.\"
.SH SEE ALSO
.BR LaTeX ,
.BR groff (1L),
.BR nroff (1),
.BR slash (1L),
.BR vamps (1L),
.BR sort (1),
.BR troff (1)
.SH AUTHORS
Raymond Venneker and Jaap Schellekens.
.br
This is free software with NO WARRANTY.
.SH BUGS
If the VAMPSLIB path is not properly set the command will fail.
Otherwise invocation has to be done from within the appropriate library
directories.
